Add documentation for the GtkLinkButton (#336592)

2006-03-30  Emmanuele Bassi  <ebassi@cvs.gnome.org>

	Add documentation for the GtkLinkButton (#336592)

	* docs/reference/tmpl/gtklinkbutton.sgml: Add description
	of the GtkLinkButton.

	* docs/reference/gtk/migrating-GtkLinkButton.sgml: Guidelines
	for migrating code from GnomeHRef to the GtkLinkButton.

	* docs/reference/gtk/gtk-docs.sgml:
	* docs/reference/gtk/Makefile.am: Build glue for the porting
	guide.

diff --git a/ChangeLog b/ChangeLog
index 9b4010964b95c2636c2eb0a2ab22c29c87141dbb..eed8ef45af1fe6bccf2b39ce23d840c0af3997f7 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2006-03-30  Emmanuele Bassi  <ebassi@cvs.gnome.org>
+
+       Add documentation for the GtkLinkButton (#336592)
+
+       * docs/reference/tmpl/gtklinkbutton.sgml: Add description
+       of the GtkLinkButton.
+
+       * docs/reference/gtk/migrating-GtkLinkButton.sgml: Guidelines
+       for migrating code from GnomeHRef to the GtkLinkButton.
+
+       * docs/reference/gtk/gtk-docs.sgml:
+       * docs/reference/gtk/Makefile.am: Build glue for the porting
+       guide.
+
 2006-03-29  Matthias Clasen <mclasen@redhat.com>
 
        * gdk/gdk.symbols:

diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10
index 9b4010964b95c2636c2eb0a2ab22c29c87141dbb..eed8ef45af1fe6bccf2b39ce23d840c0af3997f7 100644 (file)
--- a/ChangeLog.pre-2-10
+++ b/ChangeLog.pre-2-10
@@ -1,3 +1,17 @@
+2006-03-30  Emmanuele Bassi  <ebassi@cvs.gnome.org>
+
+       Add documentation for the GtkLinkButton (#336592)
+
+       * docs/reference/tmpl/gtklinkbutton.sgml: Add description
+       of the GtkLinkButton.
+
+       * docs/reference/gtk/migrating-GtkLinkButton.sgml: Guidelines
+       for migrating code from GnomeHRef to the GtkLinkButton.
+
+       * docs/reference/gtk/gtk-docs.sgml:
+       * docs/reference/gtk/Makefile.am: Build glue for the porting
+       guide.
+
 2006-03-29  Matthias Clasen <mclasen@redhat.com>
 
        * gdk/gdk.symbols:

diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index 78ee6dda7fbb4dd4e673ee77fab23b96b6816a2e..6396ea7e60251143e4026f681a6a71eaf6c19ea9 100644 (file)
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -108,6 +108,8 @@ content_files =                                     \
        migrating-GtkAboutDialog.sgml           \
        migrating-GtkColorButton.sgml           \
        migrating-GtkAssistant.sgml             \
+       migrating-GtkRecentChooser.sgml         \
+       migrating-GtkLinkButton.sgml            \
        objects_grouped.sgml                    \
        osx.sgml                                \
        question_index.sgml                     \
@@ -131,6 +133,7 @@ expand_content_files =                              \
        migrating-GtkColorButton.sgml           \
        migrating-GtkAssistant.sgml             \
        migrating-GtkRecentChooser.sgml         \
+       migrating-GtkLinkButton.sgml            \
        tree_widget.sgml                        \
        text_widget.sgml                        \
        question_index.sgml

diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index 04d2796a953b97275e0c3d53aeb98cbb2b3ada5c..794769b17e520f25f82dd10666a261228c20e48e 100644 (file)
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -210,6 +210,7 @@
 <!ENTITY gtk-migrating-GtkColorButton SYSTEM "xml/migrating-GtkColorButton.sgml">
 <!ENTITY gtk-migrating-GtkAssistant SYSTEM "xml/migrating-GtkAssistant.sgml">
 <!ENTITY gtk-migrating-GtkRecentChooser SYSTEM "xml/migrating-GtkRecentChooser.sgml">
+<!ENTITY gtk-migrating-GtkLinkButton SYSTEM "xml/migrating-GtkLinkButton.sgml">
 <!ENTITY version SYSTEM "version.xml">
 <!ENTITY gtk-query-immodules SYSTEM "gtk-query-immodules-2.0.xml">
 <!ENTITY gtk-update-icon-cache SYSTEM "gtk-update-icon-cache.xml">
@@ -615,6 +616,7 @@ that is, GUI components such as <link linkend="GtkButton">GtkButton</link> or
     &gtk-migrating-GtkColorButton;
     &gtk-migrating-GtkAssistant;
     &gtk-migrating-GtkRecentChooser;
+    &gtk-migrating-GtkLinkButton;
   </part>
 
   <part>

diff --git a/docs/reference/gtk/migrating-GtkLinkButton.sgml b/docs/reference/gtk/migrating-GtkLinkButton.sgml
new file mode 100644 (file)
index 0000000..fe8ef22
--- /dev/null
+++ b/docs/reference/gtk/migrating-GtkLinkButton.sgml
@@ -0,0 +1,72 @@
+<chapter id="gtk-migrating-GtkLinkButton">
+
+  <title>Migrating from GnomeHRef to GtkLinkButton</title>
+
+  <para>
+    Since version 2.10, GTK+ provides the #GtkLinkButton widget as a
+    replacement for the <structname>GnomeHRef</structname> widget
+    in the libgnomeui library.
+  </para>
+
+  <para>
+    Porting an application from <structname>GnomeHRef</structname> to
+    #GtkLinkButton is very simple. #GtkLinkButton does not have a
+    default action for "clicked" signal. So instead of simply creating
+    the widget
+    <informalexample><programlisting>
+      GtkWidget *button;
+
+      button = gnome_href_new (url, "");
+    </programlisting></informalexample>
+    you will have to handle the activation of the #GtkLinkButton, using
+    the "clicked" signal for instance
+    <informalexample><programlisting>
+      static void
+      link_button_clicked_cb (GtkWidget *widget,
+                              gpointer   data)
+      {
+        const gchar *link;
+
+       link = gtk_link_button_get_uri (GTK_LINK_BUTTON (widget));
+       open_browser_at_url (link);
+      }
+
+      /* ... */
+      
+        GtkWidget *button;
+
+       button = gtk_link_button_new (url);
+       g_signal_connect (button, "clicked",
+                         G_CALLBACK (link_button_clicked_cb), NULL);
+     </programlisting></informalexample>
+    If you have more than one #GtkLinkButton instead of connecting
+    a signal to each one, you can use a "hook function" which will be
+    called whenever a user activates a link button
+    <informalexample><programlisting>
+      static void
+      link_button_hook (GtkLinkButton *button,
+                        const gchar   *link,
+                       gpointer       user_data)
+      
+      {
+        open_browser_at_url (link);
+      }
+      
+      /* ... */
+      
+        GtkWidget *button1 = gtk_link_button_new (uri1);
+       GtkWidget *button2 = gtk_link_button_new (uri2);
+
+        gtk_link_button_set_uri_hook (link_button_hook, NULL, NULL);
+    </programlisting></informalexample>
+
+  </para>
+     
+</chapter>
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("gtk-docs.sgml" "book" "part" "chapter")
+End:
+-->

diff --git a/docs/reference/gtk/tmpl/gtklinkbutton.sgml b/docs/reference/gtk/tmpl/gtklinkbutton.sgml
new file mode 100644 (file)
index 0000000..68e6922
--- /dev/null
+++ b/docs/reference/gtk/tmpl/gtklinkbutton.sgml
@@ -0,0 +1,114 @@
+<!-- ##### SECTION Title ##### -->
+GtkLinkButton
+
+<!-- ##### SECTION Short_Description ##### -->
+Create buttons bound to a URL
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+A #GtkLinkButton is a #GtkButton with a hyperlink, similar to the one
+used by web browsers, which triggers an action when clicked. It is useful
+to show quick links to resources.
+</para>
+
+<para>
+A link button is created by calling either gtk_link_button_new() or
+gtk_link_button_new_with_label(). If using the former, the URI you pass
+to the constructor is used as a label for the widget.
+</para>
+
+<para>
+The URI bound to a #GtkLinkButton can be set specifically using
+gtk_link_button_set_uri(), and retrieved using gtk_link_button_get_uri().
+</para>
+
+<para>
+#GtkLinkButton offers a global hook, which is called when the used clicks
+on it: see gtk_link_button_set_uri_hook().
+</para>
+
+<para>
+#GtkLinkButton was added in GTK+ 2.10.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+#GtkButton
+</para>
+
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### STRUCT GtkLinkButton ##### -->
+<para>
+The #GtkLinkButton struct contains private data only, and should be
+manipulated using the functions below.
+</para>
+
+
+<!-- ##### ARG GtkLinkButton:uri ##### -->
+<para>
+
+</para>
+
+<!-- ##### FUNCTION gtk_link_button_new ##### -->
+<para>
+
+</para>
+
+@uri: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_link_button_new_with_label ##### -->
+<para>
+
+</para>
+
+@uri: 
+@label: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_link_button_get_uri ##### -->
+<para>
+
+</para>
+
+@link_button: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_link_button_set_uri ##### -->
+<para>
+
+</para>
+
+@link_button: 
+@uri: 
+
+
+<!-- ##### USER_FUNCTION GtkLinkButtonUriFunc ##### -->
+<para>
+The type of a function which is called when the #GtkLinkButton is
+clicked.
+</para>
+
+@button: the #GtkLinkButton which was clicked
+@link: the URI to which the clicked #GtkLinkButton points
+@data: user data that was passed when the function was registered
+  with gtk_link_button_set_uri_hook()
+
+
+<!-- ##### FUNCTION gtk_link_button_set_uri_hook ##### -->
+<para>
+
+</para>
+
+@func: 
+@data: 
+@destroy: 
+@Returns: 
+
+